/*
 * Copyright 2009 Armando Blancas
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package taskgraph.ports;

import java.io.IOException;

/**
 * An output interface to a Byte Channel.
 * 
 * @author Armando Blancas
 */
public interface ByteOutputPort extends Port {
	
    /**
     * Writes to the output stream the eight low-order bits of the argument 
     * <code>b</code>. The 24 high-order  bits of <code>b</code> are ignored.
     * 
     * @param b The byte to be written.
     * @return This output port.
     * @throws IOException  If an I/O error occurs.
     */
	ByteOutputPort write(int b) throws IOException;

    /**
     * Writes to the channel all the bytes in array <code>b</code>.
     * If <code>b</code> is <code>null</code>, a <code>NullPointerException
     * </code> is thrown. If <code>b.length</code> is zero, then no bytes are
     * written. Otherwise, the byte <code>b[0]</code> is written first, then
     * <code>b[1]</code>, and so on; the last byte written is 
     * <code>b[b.length-1]</code>.
     *
     * @param b The array data.
     * @return This output port.
     * @throws IOException  If an I/O error occurs.
     */
	ByteOutputPort write(byte[] b) throws IOException;

    /**
     * Writes <code>len</code> bytes from array <code>b</code>, in order, to
     * the channel. If <code>b</code> is <code>null</code>, a <code>
     * NullPointerException</code> is thrown.  If <code>off</code> is negative,
     * or <code>len</code> is negative, or <code>off+len</code> is greater than
     * the length of the array <code>b</code>, then an <code>
     * IndexOutOfBoundsException</code> is thrown.  If <code>len</code> is zero,
     * then no bytes are written. Otherwise, the byte <code>b[off]</code> is 
     * written first, then <code>b[off+1]</code>, and so on; the last byte 
     * written is <code>b[off+len-1]</code>.
     *
     * @param b   The array data.
     * @param off The start offset in the data.
     * @param len The number of bytes to write.
     * @return This output port.
     * @throws IOException If an I/O error occurs.
     */
	ByteOutputPort write(byte[] b, int off, int len) throws IOException;

}
